<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <title>Recovery procedures</title>
    <link rel="stylesheet" href="gettingStarted.css" type="text/css" />
    <meta name="generator" content="DocBook XSL Stylesheets V1.73.2" />
    <link rel="start" href="index.html" title="Berkeley DB Programmer's Reference Guide" />
    <link rel="up" href="transapp.html" title="Chapter 12.  Berkeley DB Transactional Data Store Applications" />
    <link rel="prev" href="transapp_logfile.html" title="Log file removal" />
    <link rel="next" href="transapp_hotfail.html" title="Hot failover" />
  </head>
  <body>
    <div xmlns="" class="navheader">
      <div class="libver">
        <p>Library Version 12.1.6.2</p>
      </div>
      <table width="100%" summary="Navigation header">
        <tr>
          <th colspan="3" align="center">Recovery procedures</th>
        </tr>
        <tr>
          <td width="20%" align="left"><a accesskey="p" href="transapp_logfile.html">Prev</a> </td>
          <th width="60%" align="center">Chapter 12.  Berkeley DB Transactional Data Store Applications </th>
          <td width="20%" align="right"> <a accesskey="n" href="transapp_hotfail.html">Next</a></td>
        </tr>
      </table>
      <hr />
    </div>
    <div class="sect1" lang="en" xml:lang="en">
      <div class="titlepage">
        <div>
          <div>
            <h2 class="title" style="clear: both"><a id="transapp_recovery"></a>Recovery procedures</h2>
          </div>
        </div>
      </div>
      <p> 
        The fifth component of the infrastructure, recovery
        procedures, concerns the recoverability of the database. After
        any application or system failure, there are two possible
        approaches to database recovery:
    </p>
      <div class="orderedlist">
        <ol type="1">
          <li>
            <p> 
                There is no need for recoverability, and all
                databases can be re-created from scratch. Although
                these applications may still need transaction
                protection for other reasons, recovery usually
                consists of removing the Berkeley DB environment home
                directory and all files it contains, and then
                restarting the application. Such an application may
                use the <a href="../api_reference/C/dbset_flags.html#dbset_flags_DB_TXN_NOT_DURABLE" class="olink">DB_TXN_NOT_DURABLE</a> flag to avoid writing log
                records.
            </p>
          </li>
          <li>
            <p> 
                It is necessary to recover information after system
                or application failure. In this case, recovery
                processing must be performed on any database
                environments that were active at the time of the
                failure. Recovery processing involves running the
                <a href="../api_reference/C/db_recover.html" class="olink">db_recover</a> utility or calling the <a href="../api_reference/C/envopen.html" class="olink">DB_ENV-&gt;open()</a> method with the
                <a href="../api_reference/C/envopen.html#envopen_DB_RECOVER" class="olink">DB_RECOVER</a> or <a href="../api_reference/C/envopen.html#envopen_DB_RECOVER_FATAL" class="olink">DB_RECOVER_FATAL</a> flags.
            </p>
            <p> 
                During recovery processing, all database changes
                made by aborted or unfinished transactions are undone,
                and all database changes made by committed
                transactions are redone, as necessary. Database
                applications must not be restarted until recovery
                completes. After recovery finishes, the environment is
                properly initialized so that applications may be
                restarted.
            </p>
          </li>
        </ol>
      </div>
      <p>
        If performing recovery, there are two types of recovery
        processing: <span class="emphasis"><em>normal</em></span> and
        <span class="emphasis"><em>catastrophic</em></span>. Which you choose
        depends on the source for the database and log files you are
        using to recover.
    </p>
      <p> 
        If up-to-the-minute database and log files are accessible
        on a stable filesystem, normal recovery is sufficient. Run the
        <a href="../api_reference/C/db_recover.html" class="olink">db_recover</a> utility or call the <a href="../api_reference/C/envopen.html" class="olink">DB_ENV-&gt;open()</a> method specifying the
        <a href="../api_reference/C/envopen.html#envopen_DB_RECOVER" class="olink">DB_RECOVER</a> flag. However, the normal recovery case <span class="bold"><strong>never</strong></span> includes recovery using hot
        backups of the database environment. For example, you cannot
        perform a hot backup of databases and log files, restore the
        backup and then run normal recovery — you must always
        run catastrophic recovery when using hot backups. 
    </p>
      <p> 
        If the database or log files have been destroyed or
        corrupted, or normal recovery fails, catastrophic recovery is
        required. For example, catastrophic failure includes the case
        where the disk drive on which the database or log files are
        stored has been physically destroyed, or when the underlying
        filesystem is corrupted and the operating system's normal
        filesystem checking procedures cannot bring that filesystem to
        a consistent state. This is often difficult to detect, and a
        common sign of the need for catastrophic recovery is when
        normal Berkeley DB recovery procedures fail, or when checksum
        errors are displayed during normal database procedures. 
    </p>
      <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
        <h3 class="title">Note</h3>
        <p>
            Berkeley DB backups (archives) can be recovered using
            machines of differing byte order. That is, a backup taken
            on a big-endian machine can be used to restore a database
            residing on a little-endian machine.
        </p>
      </div>
      <p> 
        When catastrophic recovery is necessary, take the following
        steps:
    </p>
      <div class="orderedlist">
        <ol type="1">
          <li>
            <p> 
                Restore the most recent snapshots of the database
                and log files from the backup media into the directory
                where recovery will be performed.
            </p>
          </li>
          <li>
            <p> 
                If any log files were archived since the last
                snapshot was made, they should be restored into the
                directory where recovery will be performed. 
            </p>
            <p> 
                If any log files are available from the database
                environment that failed (for example, the disk holding
                the database files crashed, but the disk holding the
                log files is fine), those log files should be copied
                into the directory where recovery will be performed.
            </p>
            <p>
                Be sure to restore all log files in the order they
                were written. The order is important because it's
                possible the same log file appears on multiple
                backups, and you want to run recovery using the most
                recent version of each log file. 
            </p>
          </li>
          <li>
            <p> 
                Run the <a href="../api_reference/C/db_recover.html" class="olink">db_recover</a> utility, specifying its <span class="bold"><strong>-c</strong></span> option; or call the
                <a href="../api_reference/C/envopen.html" class="olink">DB_ENV-&gt;open()</a> method, specifying the <a href="../api_reference/C/envopen.html#envopen_DB_RECOVER_FATAL" class="olink">DB_RECOVER_FATAL</a>
                flag. The catastrophic recovery process will review
                the logs and database files to bring the environment
                databases to a consistent state as of the time of the
                last uncorrupted log file that is found. It is
                important to realize that only transactions committed
                before that date will appear in the databases.
            </p>
            <p> 
                It is possible to re-create the database in a
                location different from the original by specifying
                appropriate pathnames to the <span class="bold"><strong>
                -h</strong></span> option of the <a href="../api_reference/C/db_recover.html" class="olink">db_recover</a> utility. In
                order for this to work properly, it is important that
                your application refer to files by names relative to
                the database home directory or the pathname(s)
                specified in calls to <a href="../api_reference/C/envadd_data_dir.html" class="olink">DB_ENV-&gt;add_data_dir()</a>, instead of
                using full pathnames. 
            </p>
          </li>
        </ol>
      </div>
    </div>
    <div class="navfooter">
      <hr />
      <table width="100%" summary="Navigation footer">
        <tr>
          <td width="40%" align="left"><a accesskey="p" href="transapp_logfile.html">Prev</a> </td>
          <td width="20%" align="center">
            <a accesskey="u" href="transapp.html">Up</a>
          </td>
          <td width="40%" align="right"> <a accesskey="n" href="transapp_hotfail.html">Next</a></td>
        </tr>
        <tr>
          <td width="40%" align="left" valign="top">Log file removal </td>
          <td width="20%" align="center">
            <a accesskey="h" href="index.html">Home</a>
          </td>
          <td width="40%" align="right" valign="top"> Hot failover</td>
        </tr>
      </table>
    </div>
  </body>
</html>
